package com.hbnu.common.dao;

import com.hbnu.common.entity.User;

import java.sql.SQLException;

/**
 * 用户数据访问对象（DAO）接口。
 * 定义了与用户相关的核心数据操作契约，包括用户注册、查询和密码更新。
 */

public interface UserDao {

    /**
     * 向数据库中新增一个用户（用户注册）。
     *
     * @param username 用户名（用户登录账号，需唯一）。
     * @param password 用户密码。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或插入操作未影响任何行，将抛出此异常。
     */
    void addUser(String username, String password) throws SQLException;

    /**
     * 根据用户名查询用户信息。
     * 常用于用户登录验证、个人信息查询等场景。
     *
     * @param username 要查询的用户名。
     * @return 包含用户信息的{@link User}实体对象，如果未找到该用户名，则返回null。
     * @throws SQLException 如果数据库连接失败或SQL执行失败，将抛出此异常。
     */
    User queryUser(String username) throws SQLException;

    /**
     * 更新指定用户的密码。
     *
     * @param username    要更新密码的用户名。
     * @param newPassword 用户的新密码。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或未找到要更新的用户，将抛出此异常。
     */
    void updatePassword(String username, String newPassword) throws SQLException;

    /**
     * 向数据库中新增一个用户（用户注册）。
     *
     * @param username 用户名（用户登录账号，需唯一）。
     * @param password 用户密码。
     * @param nickName 用户昵称。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或插入操作未影响任何行，将抛出此异常。
     */
    void addUser(String username, String password, String nickName) throws SQLException;

    /**
     * 更新指定用户的昵称。
     *
     * @param username   要更新昵称的用户名。
     * @param nickname   用户的新昵称。
     * @throws SQLException 如果数据库连接失败、SQL执行失败或未找到要更新的用户，将抛出此异常。
     */
    void updateNickname(String username, String nickname) throws SQLException;
}
